home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / shell-tools / recorder / recorder.doc < prev    next >
Encoding:
Text File  |  1996-03-27  |  7.2 KB  |  199 lines
  1.  
  2.  
  3.                   Recorder V1.2
  4.                   -------------
  5.  
  6.                  Released March, 27th 1996
  7.  
  8.  
  9.            Written and Copyright ©1991/1996 by Oliver Grimm.
  10.  
  11.  
  12.  
  13.  
  14.   1. COPYRIGHT
  15.   ============
  16.  
  17.   Both the program 'Recorder' and this documentation are copyrighted
  18.   by me, but they are public domain software. That means you can use
  19.   and spread them legally without paying any contributions (But I wouldn't
  20.   reject them, too ..) as long as everything remains unmodified, and only
  21.   the complete archive, program plus documention, is distributed.
  22.  
  23.  
  24.  
  25.   2. DISCLAIMER
  26.   =============
  27.  
  28.   As usual, no warranty for anything ...
  29.  
  30.  
  31.  
  32.   3. INTRODUCTION
  33.   ===============
  34.  
  35.   Whenever you hit a key, move the mouse, insert or remove a disk,
  36.   resize a window, or basically make any kind of input to your computer,
  37.   the operating system creates something that is called an 'input event'.
  38.   That's a structure that is sent to all programs that wish to be informed
  39.   about those things, and it includes all the information about your
  40.   action, ie. the number of the key that you have pressed, the new
  41.   position of your mouse pointer if the mouse has been moved, and so on.
  42.  
  43.   Now imagine you have to repeat the same input several times, eg. you
  44.   have to type certain commands or click certain gadgets in a specific
  45.   order, and there is, for some reason, no way in which you could
  46.   automate this, by writing a script, for instance.
  47.  
  48.   Here, this program could help you. You could start Recorder, do your
  49.   input once, and this program would save all the input events that have
  50.   been generated by you in a file. Then you could play back all these
  51.   inputs, and to all applications it will look like you are doing
  52.   all inputs again, but actually they are 'fed' into the operating
  53.   system by Recorder.
  54.  
  55.   
  56.  
  57.   4. USAGE
  58.   ========
  59.  
  60.   So far, Recorder has no GUI, so you have to start it from a command
  61.   shell.
  62.   The general parameter pattern of the program is the following, where
  63.   parameters in [] are optional and (..|..|..) means you can choose one
  64.   of the options:
  65.  
  66.  
  67.           Recorder -(r|p[q]|a[q]) FILENAME
  68.  
  69.  
  70.   There are three operating modes, record, play and append, which
  71.   are chosen by the first parameter:
  72.  
  73.     -r  Record incoming input events and store them in the
  74.         file with the name FILENAME
  75.  
  76.     -p  Play input events stored in the file FILENAME
  77.  
  78.     -a  First play input events stored in the file FILENAME,
  79.         then record more and append them to this file
  80.   
  81.   If you choose play or append, the input events are normally played
  82.   back at the same speed as they were recorded. However, when you add 'q'
  83.   to the first parameter, ie. -pq or -aq, there is a fixed delay of
  84.   1/50 second between all events.
  85.   
  86.   You have to keep in mind that the recorded events usually have some
  87.   'meaning', you might, for example, start a program by typing its name
  88.   and then click some gadgets. If you play back these input events with
  89.   the 'q' option, the start-up of the program might not be finished when
  90.   Recorder is already feeding the mouse clicks into the input stream, and
  91.   therefore the gadgets are not clicked properly because they are not
  92.   there, yet.
  93.   So be careful with this option !
  94.  
  95.   It is not necessary to use the 'Run' command to start the program.
  96.   It detaches itself automatically from the shell, so that you can
  97.   continue to work in the same shell.
  98.  
  99.   Recording does not start immediately after the program has been started,
  100.   but after you've pressed the key sequence Control-Left Amiga-'s'.
  101.   With the same sequence you can also stop recording, which
  102.   also ends the program.
  103.   Playing works similar: It's started - and stopped if you don't want
  104.   to play everything back - with Control-Left Amiga-'s'.
  105.  
  106.   In append mode, the input events are first played back normally, and
  107.   then the program switches to record mode, and you have to start recording
  108.   again with the mentioned key sequence. However, if you terminate
  109.   play back early in append mode, you can't add new events and the program
  110.   ends.
  111.  
  112.   Since Recorder always works in the background, there are not many ways
  113.   to communicate with the user without disturbing other programs.
  114.   Therefore, whenever Recorder wants to tell you something, it sends
  115.   a 'Display Beep' to all screens. 
  116.   It does so under the following circumstances:
  117.  
  118.     1) Whenever you press the control sequence to start or stop
  119.        action to acknowlege your command.
  120.     2) When play back has finished. In append mode that means that
  121.        the program is now waiting again for the control sequence
  122.        to start recording again.
  123.     3) When the second internal buffer is full and the first one
  124.        isn't written to the file yet. Then the program terminates,
  125.        and the events in the internal buffers are saved.
  126.        However, this should usually never happen, even if you are
  127.        writing to a floppy disk (see section 7).
  128.  
  129.  
  130.  
  131.   5. WHAT DOES RECORDER RECORD ?
  132.   ==============================
  133.  
  134.   Not all possible input events are recorded - it wouldn't make any
  135.   sense to record and play back a 'disk inserted' event, when there
  136.   actually hasn't been a disk inserted ! 
  137.   In fact, all that is recorded are keyboard, mousemove and mousebutton
  138.   events, so when you click a 'Load File' gadget in a program, you
  139.   still have to insert the disk yourself ! So far, Recorder can't
  140.   simulate that.  
  141.   Actually, sometimes Recorder does record an event which hasn't really
  142.   happend. It is generated by Recorder whenever you start recording.
  143.   You might have noticed that the mouse pointer sometimes 'jumps' when
  144.   you start play back. This is so because a lot of events generated
  145.   by moving the mouse only give relative positions, ie. the distance
  146.   from the last mouse position. Therefore it is necessary that the mouse
  147.   pointer is, at the beginning of playback, at the same position as it
  148.   was at the beginning of recording.
  149.   
  150.  
  151.  
  152.   6. COMPATIBILITY
  153.   ================
  154.  
  155.   The program should work on all Amiga's. If not, please drop me a note
  156.   so I can fix that.
  157.  
  158.  
  159.  
  160.   7. HOW DOES IT WORK
  161.   ===================
  162.  
  163.   This program installs, by means of the input device, an input handler
  164.   at high priority (80, in fact), so that all input events pass through
  165.   this handler (If there is no input handler at higher priority which
  166.   might filter some events).
  167.   These events are passed through unmodified, but also stored first
  168.   in a memory buffer and eventually in a file. The program actually
  169.   uses two buffers, and if one fills up the other one is used while the
  170.   first one is stored on disk, so that continuous recording is possible.
  171.   Should it happen that the second buffer fills up before the first one
  172.   has been written to the file, recording is terminated, and all the
  173.   so far recorded events are saved.
  174.   However, each buffer can hold about 1000 events, and an overflow
  175.   shouldn't occur, even if one writes to disk and moves the mouse
  176.   rapidly.
  177.   In play back mode, the stored events are fed into the input stream
  178.   by the same handler.
  179.  
  180.  
  181.  
  182.  
  183.              ----------------------
  184.  
  185.  
  186.  
  187.  
  188.   If you have any suggestions or complains, would like to have a new
  189.   function implemented, if you find any bugs or, of course, would like
  190.   to send me any gifts (A postcard, maybe ?), here's my address:
  191.  
  192.  
  193.         Oliver Grimm
  194.         Steinbecker Str.69
  195.         21244 Buchholz
  196.            Germany
  197.  
  198.             E-Mail:  grimm@physnet.uni-hamburg.de
  199.